Convergence parameters

class convergence_parameters.TNConvergenceParameters(*, max_bond_dimension=5, max_kraus_dimension=25, cut_ratio=1e-09, ini_bond_dimension=None, min_bond_dimension=1, data_type='A', device='cpu', max_iter=20, statics_method=2, abs_deviation=4e-12, rel_deviation=1e-12, n_points_conv_check=4, measure_obs_every_n_iter=-1, target_energy=None, imag_evo_dt=0.1, random_sweep=False, skip_exact_rgtensors=False, expansion_min=20, expansion_cycles=1, expansion_drop='f', de_opt_start_after_sweeps=1, de_opt_max_iter=10, de_opt_rel_deviation=1e-12, trunc_method='R', trunc_tracking_mode='C', svd_ctrl='V', min_expansion_qrte=20, arnoldi_maxiter=32, arnoldi_tolerance_fallback=0.01, arnoldi_tolerance_default=1e-15, krylov_maxiter=32, krylov_tol=1e-07, min_expansion=None, arnoldi_min_tolerance=None, arnoldi_max_tolerance=None, svd_threshold=1e-15, increase_precision=False, arnoldi_initial_tolerance=0.01, filename_conv='ConvergenceInput.dat', aggression_tolerance=1.0, aggression_expansion=1.0)

Handling of the convergence parameters for the tensor network simulations.

How-to

The arguments can be parameterized for a set of simulations, so any of the types should read as follow:

• (X, str, callable): expecting type X, but if str is passed, we check the simulation parameter dictionary’s keys or if callable we call the function with the simulation parameter dictionary.

• (X, str, callable, list): expection type X or List[X] as the parameter can be modified from sweep to sweep. If list, it has to have (at least) max_iter entries. Again, str as dictionary key or callable is allowed to generate values.

• (str, callable) and (str, callable, list) : expecting type str, if you plan to use a dictionary key, do not use one of the allowed values.

Arguments

max_bond_dimensionint | str | callable | list, optional

Maximal bond dimension, e.g., number of singular values in the ansatz. The default of 5 is meant for sketching simulations and has to be adapted according to the entanglement in the system. Default to 5.

cut_ratiofloat, optional (python side only)

Control which singular values are truncated during splitting tensors. Either relative values or truncated norm can be considered. This fine tuning can be set via trunc_method. Fortran: Not propagated through on the fortran side. Default to 1e-9

Arguments: ansatz (advanced settings)

ini_bond_dimensionint | str | callable, optional

The initial bond dimension used during the simulations when the initialization is random. The main target is statics simulations. Using subspace expansion or two-site updates the bond dimension can grow. Fortran: Not propagated through on the fortran side. Default to max_bond_dimension (via None).

min_bond_dimensionint | str | callable, optional

Set the minimum bond dimension. It is one value independent of the sweeps. It will be active during statics and dynamics and especially targets simulation which use single tensor updates. Fortran: Not propagated through on the fortran side. Default to 1.

data_typestr | callable | list, optional

Data type of the TN, which targets static simulations and can be varied for each sweep. “A” : automatic (results currently in “Z”) “Z” : double precision complex “C” : single precision complex “D” : double precision real “S” : single precision real Default to “A”

devicestr | callable | list, optional

“cpu” : run on cpu “gpu” : run on gpu “cpu+gpu” : mixed-memory mode “cgpu” : mixed-memory mode (deprecated) Fortran: no mixed-device mode available. Default to “cpu”

Arguments: statics

max_iterint | str | callable, optional

Maximum number of sweeps in the ground state search. Default to 20.

statics_methodinteger | str | callable, optional

Method to run ground state search for this/all iteration. 0 : default/auto (internally e.g., to 2 for ground state search) 1 : sweep 2 : sweep with space expansion (can still be reduced to sweep

during the simulation based on a energy condition)

3 : imaginary time evolution with two-tensor TDVP (python and fortran) 4 : imaginary time evolution with TDVP space expansion (python-only) 5 : imaginary time evolution with TDVP single-tensor (python-only) Fortran: no mode 4 and 5, but additional mode 33 for nearest-neighbor imginary time evolution via TEBD. Default to 0.

abs_deviationfloat | str | callable, optional

Exit criterion for ground state search if the energy of the current sweep has an absolute per-sweep deviation from the previous data points below this threshold: \(max(|E - E_{last}|) / n_points_conv_check < abs_deviation\) Default to 4e-12.

rel_deviationfloat, optional

Exit criterion for ground state search if the energy of the current sweep has a relative per-sweep deviation from the previous data points below this threshold. \(max(|E - E_{last}|) / n_points_conv_check < rel_deviation * |E_{last}|\) Default to 1e-12.

Arguments: statics (advanced settings)

n_points_conv_checkint, optional

Number of data points used when checking convergence, e.g., for the ground state search. Exit criteria are not checked until this many sweeps have been performed, and are never checked if n_points_conv_check > max_iter. Default to 4. It must be >= 2.

measure_obs_every_n_iterint | str | callable, optional

Modulo for measuring statics every n iterations. If -1, no additional measurements. It can be activated, but intermediate measurements are only read automatically for finite temperature. Fortran: Not propagated through on the fortran side. Default to -1 (ignored)

max_kraus_dimensionint, optional

The maximal Kraus dimension used during the simulations. The default value is purely a starting point for testing simulations. For the TTO, for example, the Kraus dimension is the dimension of the top link. Default to 25.

target_energyfloat | str | callable | None, optional

Exit criterion for ground state search if a target energy is below this threshold. Fortran: Not propagated through on the fortran side. Default to None (criterion ignored).

imag_evo_dtfloat | str | callable, optional

Time-step size for the imaginary time evolution. Default to 0.1.

random_sweepbool | str | callable | list, optional

Use random sweep scheme instead of default scheme. Default to False. Fortran: isometrization is still done, only considered if working with space-link expansion.

skip_exact_rgtensorslogical | str | callable | list, optional

Allows to skip space expansion if the tensors has already reached the maximal bond dimension, see details below. Fortran: only considered in sweeps with space-link expansion. Default to False.

Arguments: statics (advanced settings: space-link expansion)

min_expansionint | str | callable | list, optional

Amount by which the bond dimension is increased at every expansion cycle when doing link expansion. Default to 20.

expansion_cyclesint | str | callable | list, optional

For space link expansion, the link between a tensor and its predefined partner tensor are expanded. Then, each tensor and partner tensors are optimized expansion_cycles times. Default to 1.

expansion_dropstr out of [“f”, “o”, “d”] | callable | list, optional

Specifies what to do if space link expansion leads to worse energy than before with options expansion_drop=”f” for false (accept worse energies to escape local minima), “o” for optimize single tensor (reinstall original tensors, but optimize as in a single tensor update), and “d” for discarding step (reinstall original tensors and skip optimization). Fortran: Not propagated through on the fortran side. Default to “f”.

Arguments: statics (advanced settings: disentangler)

de_opt_start_after_sweepsint | str | callable, optional

Start the disentangler optimization only after performing this many sweeps without them. Fortran: Not propagated through on the fortran side. Default to 1.

de_opt_max_iterint | str | callable, optional

Maximum number of iterations for the optimization of a disentangler. Default to 10.

de_opt_rel_deviationfloat | str | callable, optional

Relative exit criterion for the disentangler optimization. Default to 1e-12.

Arguments: decompositions (advanced settings)

trunc_methodstr | callable, optional

Method use to truncate the singular values. Available: - “R”: use cut_ratio

Cut ratio \(\epsilon\) after which the singular values are neglected, i.e. if \(\lambda_1\) is the bigger singular values then after an SVD we neglect all the singular values such that \(\lambda_i/\lambda_1\leq\epsilon\).

• “N”: use maximum norm

  Maximum value of the norm neglected for the singular values during the trunctation.

Fortran: Not propagated through on the fortran side. Default to “R”

trunc_tracking_modestr | callable, optional

Modus for storing truncation, ‘M’ for maximum, ‘C’ for cumulated of the singvals squared (Norm truncated, default). Fortran: Not propagated through on the fortran side. Default to “C”

svd_ctrlcharacter | callable, optional

Control for the SVD algorithm. Available: - “A” : automatic. Some heuristic is run to choose the best mode for the algorithm.

The heuristic can be seen in tensors/tensors.py in the function _process_svd_ctrl.

• “V” : gesvd. Safe but slow method. Recommended in Fortran simulation

• “D” : gesdd. Fast iterative method. It might fail. Resort to gesvd if it fails

• “E”eigenvalue decomposition method. Faster on GPU. Available only when

  contracting the singular value to left or right

• “X”sparse eigenvalue decomposition method. Used when you reach the maximum

  bond dimension. Only python.

• “R”random SVD method. Used when you reach the maximum bond dimension.

  Only python.

Fortran: method “R” and “X” are not available. Default to “V”

min_expansion_qrte: int | float, optional

Number of expansions for QRTE decomposition. The QRTE decomposition is an alternative to the QR/SVD and a bit experimental, probably tested in qmatchatea before. For the expanding QR, in which case the value is the percentage increase (for int, value / 100; float used as is). Fortran: Not propagated through on the fortran side. Default to 20.

Arguments: Krylov solvers for statics and dynamics (advanced settings)

Note: the statics sets internally arnoldi_tolerance passed to the solvers, which cannot be modified directly and is set to machine precision inside the sweeps.

arnoldi_maxiterint | str | callable | list, optional

Maximum number of iterations in the arnoldi method. Default to 32.

arnoldi_tolerance_fallbackfloat | str | callable | list, optional

Tolerance to use if the convergence with the arnoldi_tolerance fails. Fortran: TBA Default to 1e-2.

arnoldi_tolerance_defaultfloat | str | callable | list, optional,

Default tolerance for the Arnoldi method for the single tensor if arnoldi_tolerance itself is not set. arnoldi_tolerance is set inside algorithms, but can be missing if we run eigensolver outside a ground state search or similar. Fortran: TBA optimization. Default to 1e-15.

krylov_maxiterint | str | callable, optional

For time evolution and used in the KrylovSolver. Fortran: Not propagated through on the fortran side. Default to 32.

krylov_tolfloat

Evaluated in KrylovSolver, time evolution only. Fortran: Not propagated through on the fortran side. Default to 1e-7.

Deprecated

min_expansion : see expansion_min

arnoldi_max_tolerance : see arnoldi_tolerance_fallback

arnoldi_min_tolerance : see arnoldi_tolerance_default

Fortran-only arguments

svd_thresholdfloat

TBA (only fortran side, not enabled for list)

increase_precision

TBA (not used on python side)

arnoldi_initial_tolerance

Fortran: TBA python: unused so far

filename_convstr, optional

Fortran only: the convergence parameters are saved under this filename inside the input folder. Default to ConvergenceInput.dat.

aggression_tolerance

TBA (not used on python side)

aggression_expansion

TBA (not used on python side)

Details

Skip exact renormalization group tensors

Allows to skip space expansion if the tensors has already reached the maximal bond dimension of the underlying local Hilbert spaces, i.e., full Hilbert space is captured without truncation of entanglement. It does not introduce errors itself as the tensor represents a unitary transformation with a complete orthogonal set of vector; the idea originates in the renormalization group (RG) where combining two sites is a unitary transformation as long as the new link dimension is as big as the underlying Hilbert space of all local Hilbert spaces combined. As it mostly skips operators on tensors much below the bond dimension, the benefit lies in avoiding to move the isometry (see TTN and moving through higher layers), communication overhead for sending small tensors, and in the future jit-compilation for many different bond dimensions. We aim to filter before the sweep applied; avoids even isometrizing towards the skipped tensors.

Lanczos/Krylov solvers

The Lanczos/Arnoldi solver (statics) on the qtealeaves side will interally set the tolerance to max(tolerance, eps) if the tolerance is bigger than zero and with eps being the machine precision.

property data_type

Provide the getter method for this property important to the MPS emulator. It allows to get values without a dictionary, but prevents doing it if the values is not an integer. (Not queried from the MPS for now).

get_chi(params)

Shortcut to evaluate the bond dimension as numeric parameter.

Arguments

paramsdict

The parameter dictionary for the simulation.

property max_bond_dimension

Provide the getter method for this property important to the MPS emulator. It allows to get values without a dictionary, but prevents doing it if the values is not an integer.

property min_expansion_qr

Provide the getter method for this property important to the python emulator. It is the percentage of the bond dimension increase in the qr

prepare_parameters_for_iteration(params)

Preparation to write parameters for each iteration. It checks if a list of convergence settings has to be written and builds a dictionary with the resolved entries for each parameters, which is either a the value or a list of values.

Arguments

paramsdict

Dictionary with the simulation parameters.

Results

has_vector_of_settingsbool

True if settings change over the iterations and the parameters have to be written for each iteration.

sim_param_alldict

Contains the resolved convergence parameters, i.e., strings and functions are resolved with the actual values.

resolve_params(params, idx=None)

Resolve parameterized values (inplace-update).

resolve_params_copy(params, idx=None)

Return a copy of the convergence parameters with all parameterized values resolved.

write_input(folder_name, params)

Write convergence parameters for input version 2 and 3.

Arguments

folder_namestr

Name of the input folder, where the file with the convergence parameters is written to.

paramsdict

Dictionary with the simulation parameters.

class convergence_parameters.TNConvergenceParametersFiniteT(t_grid, statics_method=4, dt_max=0.1, measure_obs_every_n_iter=20, k_b=1, **kwargs)

Convergence parameters for finite temperature. Based on the input temperature grid, the time grid for imaginary time evolution is created. The largest value of time step is limited with the input dt_max.

Parameters

t_gridlist or np.ndarray

Temperature grid, we want to take measurements for each point in the grid. The temperature grid must be sorted in descending order.

statics_methodint, optional

Only imaginary time evolution methods are enabled, i.e., 3 (two-tensor), 4 (single-tensor link-expansion), or 5 (single-tensor). Default to 4 (single-tensor link-expansion)

dt_maxfloat, optional

Maximal time step for imaginary time evolution. Default is 0.1.

measure_obs_every_n_iterint, optional

The measurements are done every measure_obs_every_n_iter iterations. The target tempertures will fall on multiples of measure_obs_every_n_iter Default is 20.

k_bfloat, optional

Value for Boltzmann constant.

**kwargs : other TNConvergenceParameters parameters

Attributes

self.sim_params[‘imag_evo_dt’]np.ndarray

Time step grid.

self.measure_obs_every_n_iterint

See Parameters above.

self.n_gridnp.ndarray of int

The number of iterations/measure_obs_every_n_iter needed to reach each of the temperatures from t_grid, starting from the infinite temperature.

property temperature

Returns the grid of temperatures at which the measurements are made. To check if the grid corresponds to the input temperature grid, use self.temperature[self.n_grid].